home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / BreakIterator.java < prev    next >
Text File  |  1998-09-22  |  15KB  |  398 lines
  1. /*
  2.  * @(#)BreakIterator.java    1.15 98/01/12
  3.  *
  4.  * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
  5.  * (C) Copyright IBM Corp. 1996 - All Rights Reserved
  6.  *
  7.  * Portions copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  8.  *
  9.  *   The original version of this source code and documentation is copyrighted
  10.  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
  11.  * materials are provided under terms of a License Agreement between Taligent
  12.  * and Sun. This technology is protected by multiple US and International
  13.  * patents. This notice and attribution to Taligent may not be removed.
  14.  *   Taligent is a registered trademark of Taligent, Inc.
  15.  *
  16.  * Permission to use, copy, modify, and distribute this software
  17.  * and its documentation for NON-COMMERCIAL purposes and without
  18.  * fee is hereby granted provided that this copyright notice
  19.  * appears in all copies. Please refer to the file "copyright.html"
  20.  * for further important copyright and licensing information.
  21.  *
  22.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  23.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  24.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  25.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  26.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  27.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  28.  *
  29.  */
  30.  
  31. package java.text;
  32. import java.util.Vector;
  33. import java.util.Locale;
  34. import java.text.resources.*;
  35.  
  36. /**
  37.  * The <code>BreakIterator</code> class implements methods for finding
  38.  * the location of boundaries in text. Instances of <code>BreakIterator</code>
  39.  * maintain a current position and scan over text
  40.  * returning the index of characters where boundaries occur.
  41.  * Internally, <code>BreakIterator</code> scans text using a
  42.  * <code>CharacterIterator</code>, and is thus able to scan text held
  43.  * by any object implementing that protocol. A <code>StringCharacterIterator</code>
  44.  * is used to scan <code>String</code> objects passed to <code>setText</code>.
  45.  *
  46.  * <p>
  47.  * You use the factory methods provided by this class to create
  48.  * instances of various types of break iterators. In particular,
  49.  * use <code>getWordIterator</code>, <code>getLineIterator</code>,
  50.  * <code>getSentenceIterator</code>, and <code>getCharacterIterator</code>
  51.  * to create <code>BreakIterator</code>s that perform
  52.  * word, line, sentence, and character boundary analysis respectively.
  53.  * A single <code>BreakIterator</code> can work only on one unit
  54.  * (word, line, sentence, and so on). You must use a different iterator
  55.  * for each unit boundary analysis you wish to perform.
  56.  *
  57.  * <p>
  58.  * Line boundary analysis determines where a text string can be
  59.  * broken when line-wrapping. The mechanism correctly handles
  60.  * punctuation and hyphenated words.
  61.  *
  62.  * <p>
  63.  * Sentence boundary analysis allows selection with correct interpretation
  64.  * of periods within numbers and abbreviations, and trailing punctuation
  65.  * marks such as quotation marks and parentheses.
  66.  *
  67.  * <p>
  68.  * Word boundary analysis is used by search and replace functions, as
  69.  * well as within text editing applications that allow the user to
  70.  * select words with a double click. Word selection provides correct
  71.  * interpretation of punctuation marks within and following
  72.  * words. Characters that are not part of a word, such as symbols
  73.  * or punctuation marks, have word-breaks on both sides.
  74.  *
  75.  * <p>
  76.  * Character boundary analysis allows users to interact with characters
  77.  * as they expect to, for example, when moving the cursor through a text
  78.  * string. Character boundary analysis provides correct navigation of
  79.  * through character strings, regardless of how the character is stored.
  80.  * For example, an accented character might be stored as a base character
  81.  * and a diacritical mark. What users consider to be a character can
  82.  * differ between languages.
  83.  *
  84.  * <p>
  85.  * <code>BreakIterator</code> is intended for use with natural
  86.  * languages only. Do not use this class to tokenize a programming language.
  87.  *
  88.  * <P>
  89.  * <strong>Examples</strong>:<P>
  90.  * Creating and using text boundaries
  91.  * <blockquote>
  92.  * <pre>
  93.  * public static void main(String args[]) {
  94.  *      if (args.length == 1) {
  95.  *          String stringToExamine = args[0];
  96.  *          //print each word in order
  97.  *          BreakIterator boundary = BreakIterator.getWordInstance();
  98.  *          boundary.setText(stringToExamine);
  99.  *          printEachForward(boundary, stringToExamine);
  100.  *          //print each sentence in reverse order
  101.  *          boundary = BreakIterator.getSentenceInstance(Locale.US);
  102.  *          boundary.setText(stringToExamine);
  103.  *          printEachBackward(boundary, stringToExamine);
  104.  *          printFirst(boundary, stringToExamine);
  105.  *          printLast(boundary, stringToExamine);
  106.  *      }
  107.  * }
  108.  * </pre>
  109.  * </blockquote>
  110.  *
  111.  * Print each element in order
  112.  * <blockquote>
  113.  * <pre>
  114.  * public static void printEachForward(BreakIterator boundary, String source) {
  115.  *     int start = boundary.first();
  116.  *     for (int end = boundary.next();
  117.  *          end != BreakIterator.DONE;
  118.  *          start = end, end = boundary.next()) {
  119.  *          System.out.println(source.substring(start,end));
  120.  *     }
  121.  * }
  122.  * </pre>
  123.  * </blockquote>
  124.  *
  125.  * Print each element in reverse order
  126.  * <blockquote>
  127.  * <pre>
  128.  * public static void printEachBackward(BreakIterator boundary, String source) {
  129.  *     int end = boundary.last();
  130.  *     for (int start = boundary.previous();
  131.  *          start != BreakIterator.DONE;
  132.  *          end = start, start = boundary.previous()) {
  133.  *         System.out.println(source.substring(start,end));
  134.  *     }
  135.  * }
  136.  * </pre>
  137.  * </blockquote>
  138.  *
  139.  * Print first element
  140.  * <blockquote>
  141.  * <pre>
  142.  * public static void printFirst(BreakIterator boundary, String source) {
  143.  *     int start = boundary.first();
  144.  *     int end = boundary.next();
  145.  *     System.out.println(source.substring(start,end));
  146.  * }
  147.  * </pre>
  148.  * </blockquote>
  149.  *
  150.  * Print last element
  151.  * <blockquote>
  152.  * <pre>
  153.  * public static void printLast(BreakIterator boundary, String source) {
  154.  *     int end = boundary.last();
  155.  *     int start = boundary.previous();
  156.  *     System.out.println(source.substring(start,end));
  157.  * }
  158.  * </pre>
  159.  * </blockquote>
  160.  *
  161.  * Print the element at a specified position
  162.  * <blockquote>
  163.  * <pre>
  164.  * public static void printAt(BreakIterator boundary, int pos, String source) {
  165.  *     int end = boundary.following(pos);
  166.  *     int start = boundary.previous();
  167.  *     System.out.println(source.substring(start,end));
  168.  * }
  169.  * </pre>
  170.  * </blockquote>
  171.  *
  172.  * @see CharacterIterator
  173.  *
  174.  */
  175.  
  176. public abstract class BreakIterator implements Cloneable, java.io.Serializable
  177. {
  178.     /**
  179.      * Constructor. BreakIterator is stateless and has no default behavior.
  180.      */
  181.     protected BreakIterator()
  182.     {
  183.     }
  184.  
  185.     /**
  186.      * Create a copy of this iterator
  187.      * @return A copy of this
  188.      */
  189.     public Object clone()
  190.     {
  191.         try {
  192.             return super.clone();
  193.         }
  194.         catch (CloneNotSupportedException e) {
  195.             throw new InternalError();
  196.         }
  197.     }
  198.  
  199.     /**
  200.      * DONE is returned by previous() and next() after all valid
  201.      * boundaries have been returned.
  202.      */
  203.     public static final int DONE = -1;
  204.  
  205.     /**
  206.      * Return the first boundary. The iterator's current position is set
  207.      * to the first boundary.
  208.      * @return The character index of the first text boundary.
  209.      */
  210.     public abstract int first()
  211.         ;
  212.     /**
  213.      * Return the last boundary. The iterator's current position is set
  214.      * to the last boundary.
  215.      * @return The character index of the last text boundary.
  216.      */
  217.     public abstract int last();
  218.  
  219.     /**
  220.      * Return the nth boundary from the current boundary
  221.      * @param n which boundary to return.  A value of 0
  222.      * does nothing.  Negative values move to previous boundaries
  223.      * and positive values move to later boundaries.
  224.      * @return The index of the nth boundary from the current position.
  225.      */
  226.     public abstract int next(int n);
  227.  
  228.     /**
  229.      * Return the boundary following the current boundary.
  230.      * @return The character index of the next text boundary or DONE if all
  231.      * boundaries have been returned.  Equivalent to next(1).
  232.      */
  233.     public abstract int next();
  234.  
  235.     /**
  236.      * Return the boundary preceding the current boundary.
  237.      * @return The character index of the previous text boundary or DONE if all
  238.      * boundaries have been returned.
  239.      */
  240.     public abstract int previous();
  241.  
  242.     /**
  243.      * Return the first boundary following the specified offset.
  244.      * The value returned is always greater than the offset or
  245.      * the value BreakIterator.DONE
  246.      * @param offset the offset to begin scanning. Valid values
  247.      * are determined by the CharacterIterator passed to
  248.      * setText().  Invalid values cause
  249.      * an IllegalArgumentException to be thrown.
  250.      * @return The first boundary after the specified offset.
  251.      */
  252.     public abstract int following(int offset);
  253.  
  254.     /**
  255.      * Return character index of the text boundary that was most recently
  256.      * returned by next(), previous(), first(), or last()
  257.      * @return The boundary most recently returned.
  258.      */
  259.     public abstract int current();
  260.  
  261.     /**
  262.      * Get the text being scanned
  263.      * @return the text being scanned
  264.      */
  265.     public abstract CharacterIterator getText();
  266.  
  267.     /**
  268.      * Set a new text string to be scanned.  The current scan
  269.      * position is reset to first().
  270.      * @param newText new text to scan.
  271.      */
  272.     public void setText(String newText)
  273.     {
  274.         setText(new StringCharacterIterator(newText));
  275.     }
  276.  
  277.     /**
  278.      * Set a new text for scanning.  The current scan
  279.      * position is reset to first().
  280.      * @param newText new text to scan.
  281.      */
  282.     public abstract void setText(CharacterIterator newText);
  283.  
  284.     /**
  285.      * Create BreakIterator for word-breaks using default locale.
  286.      * Returns an instance of a BreakIterator implementing word breaks.
  287.      * WordBreak  is usefull for word selection (ex. double click)
  288.      * @return A BreakIterator for word-breaks
  289.      * @see java.util.Locale#getDefault
  290.      */
  291.     public static BreakIterator getWordInstance()
  292.     {
  293.         return getWordInstance(Locale.getDefault());
  294.     }
  295.  
  296.     /**
  297.      * Create BreakIterator for word-breaks using specified locale.
  298.      * Returns an instance of a BreakIterator implementing word breaks.
  299.      * WordBreak is usefull for word selection (ex. double click)
  300.      * @param where the local.  If a specific WordBreak is not
  301.      * avaliable for the specified locale, a default WordBreak is returned.
  302.      * @return A BreakIterator for word-breaks
  303.      */
  304.     public static BreakIterator getWordInstance(Locale where)
  305.     {
  306.         return new SimpleTextBoundary(new WordBreakData());
  307.     }
  308.  
  309.     /**
  310.      * Create BreakIterator for line-breaks using default locale.
  311.      * Returns an instance of a BreakIterator implementing line breaks. Line
  312.      * breaks are logically possible line breaks, actual line breaks are
  313.      * usually determined based on display width.
  314.      * LineBreak is useful for word wrapping text.
  315.      * @return A BreakIterator for line-breaks
  316.      * @see java.util.Locale#getDefault
  317.      */
  318.     public static BreakIterator getLineInstance()
  319.     {
  320.         return getLineInstance(Locale.getDefault());
  321.     }
  322.  
  323.     /**
  324.      * Create BreakIterator for line-breaks using specfied locale.
  325.      * Returns an instance of a BreakIterator implementing line breaks. Line
  326.      * breaks are logically possible line breaks, actual line breaks are
  327.      * usually determined based on display width.
  328.      * LineBreak is useful for word wrapping text.
  329.      * @param where the local.  If a specific LineBreak is not
  330.      * avaliable for the specified locale, a default LineBreak is returned.
  331.      * @return A BreakIterator for line-breaks
  332.      */
  333.     public static BreakIterator getLineInstance(Locale where)
  334.     {
  335.         return new SimpleTextBoundary(new LineBreakData());
  336.     }
  337.  
  338.     /**
  339.      * Create BreakIterator for character-breaks using default locale
  340.      * Returns an instance of a BreakIterator implementing character breaks.
  341.      * Character breaks are boundaries of combining character sequences.
  342.      * @return A BreakIterator for character-breaks
  343.      * @see Locale#getDefault
  344.      */
  345.     public static BreakIterator getCharacterInstance()
  346.     {
  347.         return getCharacterInstance(Locale.getDefault());
  348.     }
  349.  
  350.     /**
  351.      * Create BreakIterator for character-breaks using specified locale
  352.      * Returns an instance of a BreakIterator implementing character breaks.
  353.      * Character breaks are boundaries of combining character sequences.
  354.      * @param where the local.  If a specific character break is not
  355.      * avaliable for the specified local, a default character break is returned.
  356.      * @return A BreakIterator for character-breaks
  357.      */
  358.     public static BreakIterator getCharacterInstance(Locale where)
  359.     {
  360.         return new SimpleTextBoundary(new CharacterBreakData());
  361.     }
  362.  
  363.     /**
  364.      * Create BreakIterator for sentence-breaks using default locale
  365.      * Returns an instance of a BreakIterator implementing sentence breaks.
  366.      * @return A BreakIterator for sentence-breaks
  367.      * @see java.util.Locale#getDefault
  368.      */
  369.     public static BreakIterator getSentenceInstance()
  370.     {
  371.         return getSentenceInstance(Locale.getDefault());
  372.     }
  373.  
  374.     /**
  375.      * Create BreakIterator for sentence-breaks using specified locale
  376.      * Returns an instance of a BreakIterator implementing sentence breaks.
  377.      * @param where the local.  If a specific SentenceBreak is not
  378.      * avaliable for the specified local, a default SentenceBreak is returned.
  379.      * @return A BreakIterator for sentence-breaks
  380.      */
  381.     public static BreakIterator getSentenceInstance(Locale where)
  382.     {
  383.         return new SimpleTextBoundary(new SentenceBreakData());
  384.     }
  385.  
  386.     /**
  387.      * Get the set of Locales for which BreakIterators are installed
  388.      * @return available locales
  389.      */
  390.     public static synchronized Locale[] getAvailableLocales()
  391.     {
  392.         //FIX ME - this is a known bug.  It should return
  393.         //all locales.
  394.         return LocaleData.getAvailableLocales("NumberPatterns");
  395.     }
  396.  
  397. }
  398.